|
Author
|
Topic: Q3 Documentation Project
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 05:44 PM 
Mainly through boredom I decided this might be a good idea... Basically this pertains to be a document detailing the operation of each useful trap engine call available with the Q3 source.I vaguely remember somebody starting something similar before and failing, most probably because it was a lot for a single person to take on. However, with a forum this isn't a problem. If everybody who is familiar with the Q3 source contributes a little bit, some passable documentation could be created very quickly. I will list the trap calls in this message and cross them off as they are documented. Perhaps when this is finished it can be reformatted into an html document to improve readability. GAME COMPLETE! CGAME trap_Print trap_Error trap_Milliseconds trap_Cvar_Register trap_Cvar_Update trap_Cvar_Set trap_Cvar_VariableStringBuffer trap_Argc trap_Argv trap_Args trap_FS_FOpenFile trap_FS_Read trap_FS_Write trap_FS_FCloseFile trap_SendConsoleCommand trap_AddCommand trap_SendClientCommand trap_UpdateScreen trap_CM_LoadMap trap_CM_NumInlineModels trap_CM_InlineModel trap_CM_LoadModel trap_CM_TempBoxModel trap_CM_PointContents trap_CM_TransformedPointContents trap_CM_BoxTrace trap_CM_TransformedBoxTrace trap_CM_MarkFragments trap_S_StartSound trap_S_StartLocalSound trap_S_ClearLoopingSounds trap_S_AddLoopingSound trap_S_UpdateEntityPosition trap_S_Respatialize trap_S_RegisterSound trap_S_StartBackgroundTrack trap_R_LoadWorldMap trap_R_RegisterModel trap_R_RegisterSkin trap_R_RegisterShader trap_R_ClearScene trap_R_AddRefEntityToScene trap_R_AddPolyToScene trap_R_AddLightToScene trap_R_RenderScene trap_R_SetColor trap_R_DrawStretchPic trap_R_ModelBounds trap_R_LerpTag trap_GetGlconfig trap_GetGameState trap_GetCurrentSnapshotNumber trap_GetSnapshot trap_GetServerCommand trap_GetCurrentCmdNumber trap_GetUserCmd trap_SetUserCmdValue trap_R_RegisterShaderNoMip trap_MemoryRemaining trap_R_RegisterFont
trap_Key_IsDown trap_Key_GetCatcher trap_Key_SetCatcher trap_Key_GetKey trap_PC_AddGlobalDefine trap_PC_LoadSource trap_PC_FreeSource trap_PC_ReadToken trap_PC_SourceFileAndLine trap_S_StopBackgroundTrack trap_RealTime trap_SnapVector
trap_RemoveCommand trap_R_LightForPoint
trap_CIN_PlayCinematic trap_CIN_StopCinematic trap_CIN_RunCinematic trap_CIN_DrawCinematic trap_CIN_SetExtents trap_R_RemapShader trap_S_AddRealLoopingSound trap_S_StopLoopingSound
Q3UI trap_Error trap_Print trap_Milliseconds trap_Cvar_Set trap_Cvar_VariableValue trap_Cvar_VariableStringBuffer trap_Cvar_SetValue trap_Cvar_Reset trap_Cvar_Create trap_Cvar_InfoStringBuffer
trap_Argc trap_Argv trap_Cmd_ExecuteText
trap_FS_FOpenFile trap_FS_Read trap_FS_Write trap_FS_FCloseFile trap_FS_GetFileList trap_R_RegisterModel trap_R_RegisterSkin trap_R_RegisterShaderNoMip trap_R_ClearScene trap_R_AddRefEntityToScene trap_R_AddPolyToScene trap_R_AddLightToScene trap_R_RenderScene trap_R_SetColor trap_R_DrawStretchPic trap_UpdateScreen trap_CM_LerpTag trap_CM_LoadModel trap_S_RegisterSound trap_S_StartLocalSound trap_Key_KeynumToStringBuf trap_Key_GetBindingBuf trap_Key_SetBinding trap_Key_IsDown trap_Key_GetOverstrikeMode trap_Key_SetOverstrikeMode trap_Key_ClearStates trap_Key_GetCatcher trap_Key_SetCatcher trap_GetClipboardData trap_GetGlconfig trap_GetClientState trap_GetConfigString trap_LAN_GetPingQueueCount trap_LAN_ClearPing trap_LAN_GetPing trap_LAN_GetPingInfo trap_Cvar_Register trap_Cvar_Update trap_MemoryRemaining trap_GetCDKey trap_SetCDKey trap_R_RegisterFont trap_R_ModelBounds trap_PC_AddGlobalDefine trap_PC_LoadSource trap_PC_FreeSource trap_PC_ReadToken trap_PC_SourceFileAndLine trap_S_StopBackgroundTrack trap_S_StartBackgroundTrack trap_RealTime trap_LAN_GetServerCount trap_LAN_GetServerAddressString trap_LAN_GetServerInfo trap_LAN_MarkServerVisible trap_LAN_UpdateVisiblePings trap_LAN_ResetPings trap_LAN_LoadCachedServers trap_LAN_SaveCachedServers trap_LAN_AddServer trap_LAN_RemoveServer
trap_CIN_PlayCinematic trap_CIN_StopCinematic trap_CIN_RunCinematic trap_CIN_DrawCinematic trap_CIN_SetExtents trap_R_RemapShader trap_VerifyCDKey trap_LAN_ServerStatus trap_LAN_GetServerPing trap_LAN_ServerIsVisible trap_LAN_CompareServers
A documentation point may be as follows: ________ BOLD: function prototype ITALIC: first parameter: its purpose ITALIC: second parameter: its purpose ... Some explanation of the trap's purpose... ________ Without further ado... [This message has been edited by Timbo : 07-02-2002.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 05:45 PM 
void trap_Printf( const char *fmt )const chat *fmt: Text to be displayed Prints the string pointed to by fmt to the Q3 Console. This should not usually be used directly by the user - the G_Printf function provides its functionality and more. [This message has been edited by Timbo : 07-31-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 05:47 PM 
void trap_Error( const char *fmt )const chat *fmt: Text to be displayed This is very simliar to the trap_Printf function with the exception that this will halt execution of the module it is called from. Usually the user shouldn't call this directly, but using G_Error instead.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 05:49 PM 
int trap_PointContents( const vec3_t point, int passEntityNum )const vec3_t point: The point in space to be examined int passEntityNum: An entityNum to be ignored. This trap call returns the CONTENTS_* of a specific point in space - it is commonly used to avoid spawning items in CONTENTS_NODROP areas. The second parameter specifies an entityNum (ent->s.number) which is ignored when evaluating the contents for a point. [This message has been edited by Timbo : 07-31-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 05:54 PM 
void trap_SetConfigstring( int num, const char *string )int num: The config string to set. const char *string: The value to set it to. The Q3 Engine provides a mechanism for communicating data from the server to the client via config strings. This is (presumably) an array of strings within the engine that are indexed by the CS_* values in bg_public.c. This trap call sets one of these strings to a value. Config strings should usually be used to communicate complex data that changes relatively rarely. [This message has been edited by Timbo : 07-31-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 06:02 PM 
void trap_GetConfigstring( int num, char *buffer, int bufferSize )int num: The config string to be read char *buffer: A pointer to a buffer to fill with the config string value. int bufferSize: The size of the buffer. This is a server side callback used to get the value of a config string. It is only used once in the q3 source, by the G_FindConfigstringIndex function which in turn is used by the G_ModelIndex and G_SoundIndex functions.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 06:13 PM 
int trap_EntitiesInBox( const vec3_t mins, const vec3_t maxs, int *list, int maxcount )const vec3_t mins: Defines the position of the corner of a cuboid. const vec3_t maxs: Defines the position of the opposite corner of this cuboid. int *list: A pointer to a list of entityNum's. int maxcount: The maximum number of entities to return. This fills an array of ints with the entity numbers (ent->s.number) of all the entities currently within the cuboid defined by mins and maxs. This is useful because it runs native and is hence significantly cheaper than doing something similar in the QVM.
|
-=Hunter-Killer=- UnRegistered |
posted 07-31-2001 06:34 PM
int trap_Milliseconds(void);No arguments needed Returns the number of milliseconds that have elapsed since Quake 3 was executed. A Quake 3, multi-platform version of the Win32 function timeGetTime, which also returns the number of milliseconds since the program was executed. [This message has been edited by -=Hunter-Killer=- : 07-31-2001.]
|
-=Hunter-Killer=- UnRegistered |
posted 07-31-2001 06:42 PM
void trap_Cvar_Register(vmCvar_t *cvar, const char *var_name, const char *value, int flags);vmCvar_t *cvar: A pointer the location in which to store the local data. const char *var_name: A null-terminated string that will be used to set the vmCvar's name field. const char *value: A null-terminated string that will be used to set both the floating point and integer value fields of the vmCvar. This function is used to create a new vmCvar. It sends all the information to the engine's main database and then it stores a local copy of the data into the vmCvar_t passed as the first argument. [This message has been edited by -=Hunter-Killer=- : 07-31-2001.]
|
-=Hunter-Killer=- UnRegistered |
posted 07-31-2001 06:50 PM
void trap_Cvar_Update(vmCvar_t *cvar);vmCvar_t *cvar: A pointer to the vmCvar to update. This function first parses out the name of the vmCvar and then searches for the corresponding database entry. Once it finds the vmCvar it will copy the "master copy" of the vmCvar into the local address provided. [This message has been edited by -=Hunter-Killer=- : 07-31-2001.]
|
-=Hunter-Killer=- UnRegistered |
posted 07-31-2001 06:56 PM
void trap_Cvar_Set(const char *var_name, const char *value);const char *var_name: A null-terminated string containing the name of the vmCvar to set. const char *value: A null-terminated string containing the desired value. This function searchs for the name of the vmCvar and stores the value into both the float and integer fields of the corresponding vmCvar entry. The only way to effectly change the value of a vmCvar is to use this function, the ANSI storage operator only modifies the local buffer and not the "master copy". [This message has been edited by -=Hunter-Killer=- : 07-31-2001.]
|
Die Insane Quaker
Posts: 345 Registered: May 2001 |
posted 07-31-2001 07:58 PM
void trap_Trace( trace_t *results, const vec3_t start, const vec3_t mins, const vec3_t maxs, const vec3_t end, int passEntityNum, int contentmask ); trace_t *results: a pointer to a variable of type trace_t where the result of the trace will be stored. const vec3_t start: a vector representing the starting position of the trace. const vec3_t mins: a vector representing the mins of the bounding box the trace will have. const vec3_t maxs: a vector representing the maxs of the bounding box the trace will have. const vec3_t end: a vector representing the end position of the trace (it's destination). int passEntityNum: the trace will not collide against the entity with this number (usually set to the entity number of the entity that initiated the trace so it won't collide against itself). int contentmask: the content mask it should collide against. Use any of the MASK_ or CONTENTS_ constants. You can logical OR several of them together if needed.
This function is used to trace from one position to another in the BSP tree and store the results in a trace_t structure. The results consist of the following information (where tr is a variable of type trace_t): tr.allsolid: if this is qtrue then the area (or some part of it) between the mins and maxs is inside a solid (a brush). tr.contents: the contents mask of the plane that the trace hit. tr.endpos: position where the trace ended. tr.entityNum: entity number of the entity that the trace hit (if it hit solid geometry then this will equal ENTITYNUM_WORLD). tr.fraction: this is the fraction of the vector between start and end where the trace ended. Therefore if this is less than 1.0 the trace hit something. tr.plane: contains information about the plane that was hit (most notably the surface normal) stored in a cplane_t structure. tr.startsolid: if this is qtrue then the trace started in a solid (brush). tr.surfaceFlags: surfaceflags of the surface that was hit (look in surfaceflags.h at the SURF_* constants to see the which ones there are). If the mins and maxs are NULL then the trace is treated as purely linear from point to point. If mins and maxs are defined however a bounding box trace is performed whereby rather than a point the entire bounding box is traced so that it is possible to detect the collision between solid entities. For example, tracing directly downwards onto a floor with mins and maxs set to { -15, -15, -15 } and { 15, 15, 15 } respectively starting at some point above the floor will result in a trace_t with an endpoint 15 units from the floor. [This message has been edited by Timbo : 08-24-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 09:48 PM 
int trap_Argc( void )Whenever a client issues a console command it can have arguments passed with it. This function returns the number of arguments identically to the argc found in C programs with this prototype for main: int main( int argc, char **argv ) [This message has been edited by Timbo : 08-20-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 07-31-2001 09:54 PM 
void trap_Argv( int n, char *buffer, int bufferLength )int n: The argument number to return. char *buffer: A point to a buffer to fill. int bufferLength: The size of the buffer. This will fill the buffer pointed to by buffer with an argument to a client command where n is the argument to return. 0 is the command itself, 1 is the first argument and so on... Very similiar to char **argv in a C program.
|
-=Hunter-Killer=- UnRegistered |
posted 08-01-2001 08:49 AM
int trap_Cvar_VariableIntegerValue( const char *var_name );const char *var_name: A null-terminated string containing the name of the vmCvar to retrieve a value from. This function returns the integer value of var_name that is currently stored in the "master copy". [This message has been edited by -=Hunter-Killer=- : 08-01-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-01-2001 11:31 AM 
int trap_FS_FOpenFile( const char *qpath, fileHandle_t *f, fsMode_t mode )const char *qpath: The file to be opened. fileHandle_t *f: Reference to a local fileHandle_t. fsMode_t mode: Mode to open the file in. This opens a file specified by the string qpath and allocates a fileHandle_t (just a typedef int) to that file. This is then used in subsequent operations involving the file. The fsMode_t enumeration refers to the mode the file is opened in. FS_READ for reading the file. FS_WRITE will create the file qpath if it doesn't exist or 0 length it if it does. FS_APPEND allows writing to the end of an existing file. FS_APPEND_SYNC is similar to FS_APPEND except you can read from the file at the same time. An int is returned representing the length of the file being opened. [This message has been edited by Timbo : 08-01-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-01-2001 11:32 AM 
void trap_FS_Read( void *buffer, int len, fileHandle_t f )void *buffer: A buffer to fill. int len: The amount to read from the file. fileHandle_t: A file handle provided by trap_FS_FOpenFile. This reads len bytes of data from the file specified by f and fills buffer with it.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-01-2001 11:32 AM 
void trap_FS_Write( const void *buffer, int len, fileHandle_t f )const void *buffer: A buffer to read from. int len: The amount to write to the file. fileHandle_t: A file handle provided by trap_FS_FOpenFile. This writes len bytes of data from buffer to the file specified by f.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-01-2001 11:33 AM 
trap_FS_FCloseFile( fileHandle_t f )fileHandle_t f: The file to be closed. Closes the file specified by f.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:03 PM 
void trap_SendConsoleCommand( int exec_when, const char *text )int exec_when: When to execute this command. const char *text: The command to be executed. This call adds a command to the command buffer i.e. so that the programmer may issue server commands that would normally need to be entered into the console. exec_when takes an element of the cbufExec_t enumeration: code:
// paramters for command buffer stuffing typedef enum { EXEC_NOW, // don't return until completed, a VM should NEVER use this, // because some commands might cause the VM to be unloaded... EXEC_INSERT, // insert at current position, but don't run yet EXEC_APPEND // add to end of the command buffer (normal case) } cbufExec_t;
[This message has been edited by Timbo : 08-03-2001.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:05 PM 
void trap_LocateGameData( gentity_t *gEnts, int numGEntities, int sizeofGEntity_t, playerState_t *gameClients, int sizeofGameClient )gentity_t *gEnts: Usually level.gentities. int numGEntities: Usually level.num_entities. int sizeofGEntity_t: Usually sizeof( gentity_t ). playerState_t *gameClients: Usually &level.clients;[0].ps. int sizeofGameClient: Usually sizeof( level.clients[0] ). It would be very unusual for a mod programmer to want to call this - especially with parameters other than those outlined above. Its purpose it to notify the Q3 binary when new entities are created. In the Q3 source it is used twice - once on level load and in G_Spawn where it is called whenever an entity is created.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:05 PM 
void trap_DropClient( int clientNum, const char *reason )int clientNum: The client to drop. const char *reason: The reason for the drop. This provides a mechanism to unconditionally drop a client from a server via their clientNum ( ent->client->ps.clientNum). The reason is displayed to the client when they are dropped.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:06 PM 
void trap_SendServerCommand( int clientNum, const char *text )int clientNum: The client that the command is being sent from. const char *text: The command to be sent. This has the same effect as typing a command in a clients console for evaluation by the server. This includes the commands evaluated in g_cmds.c. Its main use in the Q3 source is to print information to a specific client's console via the "print" command. Passing -1 as the clientNum sends the command to every client.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:06 PM 
void trap_LinkEntity( gentity_t *ent )gentity_t *ent: Entity to be linked. When an entity is "linked" it is subject to all evaluations that the world performs on it. For example, all linked entities are accounted for when performing a trace. Newly created entities are not linked into the world - they must be explcitly linked using this call. Linking an entity that is already linked into the world has no effect unless the following properties have changed:
- Its origin or angles have changed which might cause a change in the entity's PVS (ent->r.currentOrigin is used to calculate the entity's PVS cluster)
- Its bounds have changed (again, is used in PVS cluster calculations, and to set abs(min/max))
- Its contents have changed (will set ent->s.solid)
- Its brush model has changed (again, sets ent->s.solid)
[This message has been edited by Timbo : 03-21-2003.]
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-03-2001 12:07 PM 
void trap_UnlinkEntity( gentity_t *ent )gentity_t *ent: Entity to be unlinked. When an entity is "unlinked" from the world it remains in memory, but ceases to exist from the point of view of the world. This is useful for temporarily deleting an entity or when performing major alterations to an entity's fields. Unlinking an entity that is already unlinked has no effect.
|
FonFon Rookie
Posts: 47 Registered: Jan 2001 |
posted 08-04-2001 10:27 AM
qboolean trap_InPVS( const vec3_t p1, const vec3_t p2 )const vec3_t p1: Absolute coordinates of point 1 const vec3_t p2:Absolute coordinates of point 2 Returns true if point1 can _potentially_ see point2. Two points can return true, but not be visible to each other due to detail brushes, curves, etc. A return value of false guarantees that the points can not see each other. Normally used to test if two entities can potentially see each other, point1 would be the currentOrigin of the first entitiy and point2 the currentOrigin of the second entity. This function relies on the Potentially Visible Set, and areaportal data generated during the BSP compiling of a map.
|
FonFon Rookie
Posts: 47 Registered: Jan 2001 |
posted 08-04-2001 10:28 AM
qboolean trap_InPVSIgnorePortals( const vec3_t p1, const vec3_t p2 )const vec3_t p1: Absolute coordinates of point 1 const vec3_t p2: Absolute coordinates of point 2 Returns true if point1 can _potentially_ see point2. This function does not check areaportals. Points hidden by closed doors (and other areaportals) will still return true.
|
FonFon Rookie
Posts: 47 Registered: Jan 2001 |
posted 08-04-2001 10:30 AM
void trap_AdjustAreaPortalState( gentity_t *ent, qboolean open )gentity_t *ent: Entity to adjust qboolean open: State to adjust to Adjusts the state of a portal connecting two areas. Set "open" to true to allow visibility through the portal and false to block visibility. This is normally used to adjust visibility when opening and closing doors. When the door is open; "open" is set true and entities are visible through the door, when the door is closed; "open" is set false and trap_InPVS will not see entities through the door. See Use_BinaryMover in the game source for an example.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-10-2001 10:01 AM 
void trap_GetUserinfo( int num, char *buffer, int bufferSize )int num: clientNum of the userinfo to retrieve. char *buffer: Pointer to a buffer to fill. int buffersize: Size of the buffer. Each client has a "user info" string which is a backslash delimited key/value pair for the various options the user can set. For example, model, skin and weapon colour. trap_GetUserinfo fills the buffer pointed to by *buffer with the userinfo of the client referenced by num. Key values are then retrieved using Info_ValueForKey( buffer, keyname ).
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-10-2001 10:02 AM 
void trap_SetUserinfo( int num, const char *buffer )int num: clientNum of userinfo to change. const char *buffer: Userinfo string to set. This does the opposite to trap_GetUserinfo and sets a userinfo string for a user. However, it is not used much in the Q3 source, where config strings seem to be the prefered method to transfer userinfo to the client.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-10-2001 10:02 AM 
void trap_GetServerinfo( char *buffer, int bufferSize )char *buffer: A buffer to fill with the server info. int bufferSize: The size of the buffer. The "server info" string is a backslash delimited list of server variables such as g_gametype and mapname. Besides the bot code, its only other use in the Q3 source is to print to the value of serverinfo to the logfile.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-19-2001 05:57 PM 
qboolean trap_AreasConnected( int area1, int area2 )int area1: First area to test. int area2: Second area to test. This functions tests whether or not the areas (presumably leaf nodes of the bsp tree) are adjacent physically. FIXME: the values of area1 and area2 are unknown, however.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-19-2001 05:58 PM 
qboolean trap_EntityContactCapsule( const vec3_t mins, const vec3_t maxs, const gentity_t *ent )const vec3_t mins: Lower bounds. const vec3_t maxs: Upper bounds. const gentity_t *ent: The entity to test. If the entity pointed to by ent is physically within the bounds specified by mins and maxs then this function returns qtrue.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-19-2001 05:59 PM 
void trap_GetUsercmd( int clientNum, usercmd_t *cmd )int clientNum: The clientNum to retreive cmd from. usercmd_t *cmd: Pointer to a usercmd_t to fill. This function will retrieve the usercmd_t generated by the client portion of the Q3 binary and place it in what it pointed to by cmd.
|
Timbo Linux+Quake=Good
Posts: 923 Registered: Jun 2000 |
posted 08-19-2001 05:59 PM 
qboolean trap_GetEntityToken( char *buffer, int bufferSize )char *buffer: A buffer to fill. int bufferSize: The size of the buffer. This call fills the buffer pointed to by buffer with all the key/value pairs of every map entity. The string returned has a very similar format to that of the tail end of a GTKRadiant .map file before it is compiled to a bsp. It is unlikely that a user would ever need to call this since it is handled already in g_spawn.c
|